
<!DOCTYPE html>
<html>
<head>
    <META http-equiv="Content-Type" content="text/html; charset=UTF-8">
    <title>ZooKeeper: Because Coordinating Distributed Systems is a Zoo</title>
    <link type="text/css" href="skin/basic.css" rel="stylesheet">
    <link media="screen" type="text/css" href="skin/screen.css" rel="stylesheet">
    <link media="print" type="text/css" href="skin/print.css" rel="stylesheet">
    <link type="text/css" href="skin/profile.css" rel="stylesheet">
    <script src="skin/getBlank.js" language="javascript" type="text/javascript"></script>
    <script src="skin/getMenu.js" language="javascript" type="text/javascript"></script>
    <script src="skin/init.js" language="javascript" type="text/javascript"></script>
    <link rel="shortcut icon" href="images/favicon.ico">
</head>
<body onload="init();">
<div id="top">
    <div class="breadtrail">
        <a href="http://www.apache.org/">Apache</a> &gt; <a href="http://zookeeper.apache.org/">ZooKeeper</a>
    </div>
    <div class="header">
        <div class="projectlogo">
            <a href="http://zookeeper.apache.org/"><img class="logoImage" alt="ZooKeeper" src="images/zookeeper_small.gif" title="ZooKeeper: distributed coordination"></a>
        </div>
        <div class="searchbox">
            <form action="http://www.google.com/search" method="get">
                <input value="zookeeper.apache.org" name="sitesearch" type="hidden"><input onFocus="getBlank (this, 'Search the site with google');" size="25" name="q" id="query" type="text" value="Search the site with google">&nbsp;
                <input name="Search" value="Search" type="submit">
            </form>
        </div>
        <ul id="tabs">
            <li>
                <a class="unselected" href="http://zookeeper.apache.org/">Project</a>
            </li>
            <li>
                <a class="unselected" href="https://cwiki.apache.org/confluence/display/ZOOKEEPER/">Wiki</a>
            </li>
            <li class="current">
                <a class="selected" href="index.html">ZooKeeper 3.5 Documentation</a>
            </li>
        </ul>
    </div>
</div>
<div id="main">
    <div id="publishedStrip">
        <div id="level2tabs"></div>
        <script type="text/javascript"><!--
document.write("Last Published: " + document.lastModified);
//  --></script>
    </div>
    <div class="breadtrail">
        &nbsp;
    </div>
    <div id="menu">
        <div onclick="SwitchMenu('menu_1', 'skin/')" id="menu_1Title" class="menutitle">Overview</div>
        <div id="menu_1" class="menuitemgroup">
            <div class="menuitem">
                <a href="index.html">Welcome</a>
            </div>
            <div class="menuitem">
                <a href="zookeeperOver.html">Overview</a>
            </div>
            <div class="menuitem">
                <a href="zookeeperStarted.html">Getting Started</a>
            </div>
            <div class="menuitem">
                <a href="releasenotes.html">Release Notes</a>
            </div>
        </div>
        <div onclick="SwitchMenu('menu_2', 'skin/')" id="menu_2Title" class="menutitle">Developer</div>
        <div id="menu_2" class="menuitemgroup">
            <div class="menuitem">
                <a href="apidocs/zookeeper-server/index.html">API Docs</a>
            </div>
            <div class="menuitem">
                <a href="zookeeperProgrammers.html">Programmer's Guide</a>
            </div>
            <div class="menuitem">
                <a href="javaExample.html">Java Example</a>
            </div>
            <div class="menuitem">
                <a href="zookeeperTutorial.html">Barrier and Queue Tutorial</a>
            </div>
            <div class="menuitem">
                <a href="recipes.html">Recipes</a>
            </div>
        </div>
        <div onclick="SwitchMenu('menu_3', 'skin/')" id="menu_3Title" class="menutitle">Admin &amp; Ops</div>
        <div id="menu_3" class="menuitemgroup">
            <div class="menuitem">
                <a href="zookeeperAdmin.html">Administrator's Guide</a>
            </div>
            <div class="menuitem">
                <a href="zookeeperQuotas.html">Quota Guide</a>
            </div>
            <div class="menuitem">
                <a href="zookeeperJMX.html">JMX</a>
            </div>
            <div class="menuitem">
                <a href="zookeeperObservers.html">Observers Guide</a>
            </div>
            <div class="menuitem">
                <a href="zookeeperReconfig.html">Dynamic Reconfiguration</a>
            </div>
        </div>
        <div onclick="SwitchMenu('menu_4', 'skin/')" id="menu_4Title" class="menutitle">Contributor</div>
        <div id="menu_4" class="menuitemgroup">
            <div class="menuitem">
                <a href="zookeeperInternals.html">ZooKeeper Internals</a>
            </div>
        </div>
        <div onclick="SwitchMenu('menu_5', 'skin/')" id="menu_5Title" class="menutitle">Miscellaneous</div>
        <div id="menu_5" class="menuitemgroup">
            <div class="menuitem">
                <a href="https://cwiki.apache.org/confluence/display/ZOOKEEPER">Wiki</a>
            </div>
            <div class="menuitem">
                <a href="https://cwiki.apache.org/confluence/display/ZOOKEEPER/FAQ">FAQ</a>
            </div>
            <div class="menuitem">
                <a href="http://zookeeper.apache.org/mailing_lists.html">Mailing Lists</a>
            </div>
        </div>
    </div>
    <div id="content">
<!--
Copyright 2002-2004 The Apache Software Foundation

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
//-->
<h1>ZooKeeper Administrator's Guide</h1>
<h3>A Guide to Deployment and Administration</h3>
<ul>
<li><a href="#ch_deployment">Deployment</a>
<ul>
<li><a href="#sc_systemReq">System Requirements</a>
<ul>
<li><a href="#sc_supportedPlatforms">Supported Platforms</a></li>
<li><a href="#sc_requiredSoftware">Required Software</a></li>
</ul>
</li>
<li><a href="#sc_zkMulitServerSetup">Clustered (Multi-Server) Setup</a></li>
<li><a href="#sc_singleAndDevSetup">Single Server and Developer Setup</a></li>
</ul>
</li>
<li><a href="#ch_administration">Administration</a>
<ul>
<li><a href="#sc_designing">Designing a ZooKeeper Deployment</a>
<ul>
<li><a href="#sc_CrossMachineRequirements">Cross Machine Requirements</a></li>
<li><a href="#Single+Machine+Requirements">Single Machine Requirements</a></li>
</ul>
</li>
<li><a href="#sc_provisioning">Provisioning</a></li>
<li><a href="#sc_strengthsAndLimitations">Things to Consider: ZooKeeper Strengths and Limitations</a></li>
<li><a href="#sc_administering">Administering</a></li>
<li><a href="#sc_maintenance">Maintenance</a>
<ul>
<li><a href="#Ongoing+Data+Directory+Cleanup">Ongoing Data Directory Cleanup</a></li>
<li><a href="#Debug+Log+Cleanup+%28log4j%29">Debug Log Cleanup (log4j)</a></li>
</ul>
</li>
<li><a href="#sc_supervision">Supervision</a></li>
<li><a href="#sc_monitoring">Monitoring</a></li>
<li><a href="#sc_logging">Logging</a></li>
<li><a href="#sc_troubleshooting">Troubleshooting</a></li>
<li><a href="#sc_configuration">Configuration Parameters</a>
<ul>
<li><a href="#sc_minimumConfiguration">Minimum Configuration</a></li>
<li><a href="#sc_advancedConfiguration">Advanced Configuration</a></li>
<li><a href="#sc_clusterOptions">Cluster Options</a></li>
<li><a href="#sc_authOptions">Encryption, Authentication, Authorization Options</a></li>
<li><a href="#Experimental+Options%2FFeatures">Experimental Options/Features</a></li>
<li><a href="#Unsafe+Options">Unsafe Options</a></li>
<li><a href="#Disabling+data+directory+autocreation">Disabling data directory autocreation</a></li>
<li><a href="#sc_db_existence_validation">Enabling db existence validation</a></li>
<li><a href="#sc_performance_options">Performance Tuning Options</a></li>
<li><a href="#sc_adminserver_config">AdminServer configuration</a></li>
</ul>
</li>
<li><a href="#Communication+using+the+Netty+framework">Communication using the Netty framework</a>
<ul>
<li><a href="#Quorum+TLS">Quorum TLS</a></li>
<li><a href="#Upgrading+existing+nonTLS+cluster">Upgrading existing non-TLS cluster with no downtime</a></li>
</ul>
</li>
<li><a href="#sc_zkCommands">ZooKeeper Commands</a>
<ul>
<li><a href="#sc_4lw">The Four Letter Words</a></li>
<li><a href="#sc_adminserver">The AdminServer</a></li>
</ul>
</li>
<li><a href="#sc_dataFileManagement">Data File Management</a>
<ul>
<li><a href="#The+Data+Directory">The Data Directory</a></li>
<li><a href="#The+Log+Directory">The Log Directory</a></li>
<li><a href="#sc_filemanagement">File Management</a></li>
<li><a href="#Recovery+-+TxnLogToolkit">Recovery - TxnLogToolkit</a></li>
</ul>
</li>
<li><a href="#sc_commonProblems">Things to Avoid</a></li>
<li><a href="#sc_bestPractices">Best Practices</a></li>
</ul>
</li>
</ul>
<p><a name="ch_deployment"></a></p>
<h2>Deployment</h2>
<p>This section contains information about deploying Zookeeper and covers these topics:</p>
<ul>
<li><a href="#sc_systemReq">System Requirements</a></li>
<li><a href="#sc_zkMulitServerSetup">Clustered (Multi-Server) Setup</a></li>
<li><a href="#sc_singleAndDevSetup">Single Server and Developer Setup</a></li>
</ul>
<p>The first two sections assume you are interested in installing ZooKeeper in a production environment such as a datacenter. The final section covers situations in which you are setting up ZooKeeper on a limited basis - for evaluation, testing, or development - but not in a production environment.</p>
<p><a name="sc_systemReq"></a></p>
<h3>System Requirements</h3>
<p><a name="sc_supportedPlatforms"></a></p>
<h4>Supported Platforms</h4>
<p>ZooKeeper consists of multiple components.  Some components are supported broadly, and other components are supported only on a smaller set of platforms.</p>
<ul>
<li><strong>Client</strong> is the Java client library, used by applications to connect to a ZooKeeper ensemble.</li>
<li><strong>Server</strong> is the Java server that runs on the ZooKeeper ensemble nodes.</li>
<li><strong>Native Client</strong> is a client implemented in C, similar to the Java client, used by applications to connect to a ZooKeeper ensemble.</li>
<li><strong>Contrib</strong> refers to multiple optional add-on components.</li>
</ul>
<p>The following matrix describes the level of support committed for running each component on different operating system platforms.</p>
<h5>Support Matrix</h5>
<table>
<thead>
<tr><th> Operating System </th><th> Client </th><th> Server </th><th> Native Client </th><th> Contrib </th></tr>
</thead>
<tbody>
<tr><td> GNU/Linux </td><td> Development and Production </td><td> Development and Production </td><td> Development and Production </td><td> Development and Production </td></tr>
<tr><td> Solaris </td><td> Development and Production </td><td> Development and Production </td><td> Not Supported </td><td> Not Supported </td></tr>
<tr><td> FreeBSD </td><td> Development and Production </td><td> Development and Production </td><td> Not Supported </td><td> Not Supported </td></tr>
<tr><td> Windows </td><td> Development and Production </td><td> Development and Production </td><td> Not Supported </td><td> Not Supported </td></tr>
<tr><td> Mac OS X </td><td> Development Only </td><td> Development Only </td><td> Not Supported </td><td> Not Supported </td></tr>
</tbody>
</table>
<p>For any operating system not explicitly mentioned as supported in the matrix, components may or may not work.  The ZooKeeper community will fix obvious bugs that are reported for other platforms, but there is no full support.</p>
<p><a name="sc_requiredSoftware"></a></p>
<h4>Required Software</h4>
<p>ZooKeeper runs in Java, release 1.7 or greater (JDK 7 or greater, FreeBSD support requires openjdk7).  It runs as an <em>ensemble</em> of ZooKeeper servers. Three ZooKeeper servers is the minimum recommended size for an ensemble, and we also recommend that they run on separate machines. At Yahoo!, ZooKeeper is usually deployed on dedicated RHEL boxes, with dual-core processors, 2GB of RAM, and 80GB IDE hard drives.</p>
<p><a name="sc_zkMulitServerSetup"></a></p>
<h3>Clustered (Multi-Server) Setup</h3>
<p>For reliable ZooKeeper service, you should deploy ZooKeeper in a cluster known as an <em>ensemble</em>. As long as a majority of the ensemble are up, the service will be available. Because Zookeeper requires a majority, it is best to use an odd number of machines. For example, with four machines ZooKeeper can only handle the failure of a single machine; if two machines fail, the remaining two machines do not constitute a majority. However, with five machines ZooKeeper can handle the failure of two machines.</p>
<h6>Note</h6>
<blockquote>
<p>As mentioned in the <a href="zookeeperStarted.html">ZooKeeper Getting Started Guide</a> , a minimum of three servers are required for a fault tolerant clustered setup, and it is strongly recommended that you have an odd number of servers.</p>
<p>Usually three servers is more than enough for a production install, but for maximum reliability during maintenance, you may wish to install five servers. With three servers, if you perform maintenance on one of them, you are vulnerable to a failure on one of the other two servers during that maintenance. If you have five of them running, you can take one down for maintenance, and know that you're still OK if one of the other four suddenly fails.</p>
<p>Your redundancy considerations should include all aspects of your environment. If you have three ZooKeeper servers, but their network cables are all plugged into the same network switch, then the failure of that switch will take down your entire ensemble.</p>
</blockquote>
<p>Here are the steps to setting a server that will be part of an ensemble. These steps should be performed on every host in the ensemble:</p>
<ol>
<li>
<p>Install the Java JDK. You can use the native packaging system for your system, or download the JDK from: <a href="http://java.sun.com/javase/downloads/index.jsp">http://java.sun.com/javase/downloads/index.jsp</a></p>
</li>
<li>
<p>Set the Java heap size. This is very important to avoid swapping, which will seriously degrade ZooKeeper performance. To determine the correct value, use load tests, and make sure you are well below the usage limit that would cause you to swap. Be conservative - use a maximum heap size of 3GB for a 4GB machine.</p>
</li>
<li>
<p>Install the ZooKeeper Server Package. It can be downloaded from: <a href="http://zookeeper.apache.org/releases.html">http://zookeeper.apache.org/releases.html</a></p>
</li>
<li>
<p>Create a configuration file. This file can be called anything. Use the following settings as a starting point:</p>
<pre><code>tickTime=2000
dataDir=/var/lib/zookeeper/
clientPort=2181
initLimit=5
syncLimit=2
server.1=zoo1:2888:3888
server.2=zoo2:2888:3888
server.3=zoo3:2888:3888
</code></pre>
<p>You can find the meanings of these and other configuration settings in the section <a href="#sc_configuration">Configuration Parameters</a>. A word though about a few here: Every machine that is part of the ZooKeeper ensemble should know about every other machine in the ensemble. You accomplish this with the series of lines of the form <strong>server.id=host:port:port</strong>. The parameters <strong>host</strong> and <strong>port</strong> are straightforward. You attribute the server id to each machine by creating a file named <em>myid</em>, one for each server, which resides in that server's data directory, as specified by the configuration file parameter <strong>dataDir</strong>.</p>
</li>
<li>
<p>The myid file consists of a single line containing only the text of that machine's id. So <em>myid</em> of server 1 would contain the text &quot;1&quot; and nothing else. The id must be unique within the ensemble and should have a value between 1 and 255. <strong>IMPORTANT:</strong> if you enable extended features such as TTL Nodes (see below) the id must be between 1 and 254 due to internal limitations.</p>
</li>
<li>
<p>If your configuration file is set up, you can start a ZooKeeper server:</p>
<pre><code>$ java -cp zookeeper.jar:lib/*:conf org.apache.zookeeper.server.quorum.QuorumPeerMain zoo.conf 
</code></pre>
</li>
</ol>
<p>QuorumPeerMain starts a ZooKeeper server, <a href="http://java.sun.com/javase/technologies/core/mntr-mgmt/javamanagement/">JMX</a> management beans are also registered which allows management through a JMX management console. The <a href="zookeeperJMX.html">ZooKeeper JMX document</a> contains details on managing ZooKeeper with JMX. See the script <em>bin/zkServer.sh</em>, which is included in the release, for an example of starting server instances.</p>
<ol>
<li>Test your deployment by connecting to the hosts: In Java, you can run the following command to execute simple operations:
<pre><code>$ bin/zkCli.sh -server 127.0.0.1:2181
</code></pre>
</li>
</ol>
<p><a name="sc_singleAndDevSetup"></a></p>
<h3>Single Server and Developer Setup</h3>
<p>If you want to setup ZooKeeper for development purposes, you will probably want to setup a single server instance of ZooKeeper, and then install either the Java or C client-side libraries and bindings on your development machine.</p>
<p>The steps to setting up a single server instance are the similar to the above, except the configuration file is simpler. You can find the complete instructions in the <a href="zookeeperStarted.html#sc_InstallingSingleMode">Installing and Running ZooKeeper in Single Server Mode</a> section of the <a href="zookeeperStarted.html">ZooKeeper Getting Started Guide</a>.</p>
<p>For information on installing the client side libraries, refer to the <a href="zookeeperProgrammers.html#ch_bindings">Bindings</a> section of the <a href="zookeeperProgrammers.html">ZooKeeper Programmer's Guide</a>.</p>
<p><a name="ch_administration"></a></p>
<h2>Administration</h2>
<p>This section contains information about running and maintaining ZooKeeper and covers these topics:</p>
<ul>
<li><a href="#sc_designing">Designing a ZooKeeper Deployment</a></li>
<li><a href="#sc_provisioning">Provisioning</a></li>
<li><a href="#sc_strengthsAndLimitations">Things to Consider: ZooKeeper Strengths and Limitations</a></li>
<li><a href="#sc_administering">Administering</a></li>
<li><a href="#sc_maintenance">Maintenance</a></li>
<li><a href="#sc_supervision">Supervision</a></li>
<li><a href="#sc_monitoring">Monitoring</a></li>
<li><a href="#sc_logging">Logging</a></li>
<li><a href="#sc_troubleshooting">Troubleshooting</a></li>
<li><a href="#sc_configuration">Configuration Parameters</a></li>
<li><a href="#sc_zkCommands">ZooKeeper Commands</a></li>
<li><a href="#sc_dataFileManagement">Data File Management</a></li>
<li><a href="#sc_commonProblems">Things to Avoid</a></li>
<li><a href="#sc_bestPractices">Best Practices</a></li>
</ul>
<p><a name="sc_designing"></a></p>
<h3>Designing a ZooKeeper Deployment</h3>
<p>The reliability of ZooKeeper rests on two basic assumptions.</p>
<ol>
<li>Only a minority of servers in a deployment will fail. <em>Failure</em> in this context means a machine crash, or some error in the network that partitions a server off from the majority.</li>
<li>Deployed machines operate correctly. To operate correctly means to execute code correctly, to have clocks that work properly, and to have storage and network components that perform consistently.</li>
</ol>
<p>The sections below contain considerations for ZooKeeper administrators to maximize the probability for these assumptions to hold true. Some of these are cross-machines considerations, and others are things you should consider for each and every machine in your deployment.</p>
<p><a name="sc_CrossMachineRequirements"></a></p>
<h4>Cross Machine Requirements</h4>
<p>For the ZooKeeper service to be active, there must be a majority of non-failing machines that can communicate with each other. To create a deployment that can tolerate the failure of F machines, you should count on deploying 2xF+1 machines.  Thus, a deployment that consists of three machines can handle one failure, and a deployment of five machines can handle two failures. Note that a deployment of six machines can only handle two failures since three machines is not a majority.  For this reason, ZooKeeper deployments are usually made up of an odd number of machines.</p>
<p>To achieve the highest probability of tolerating a failure you should try to make machine failures independent. For example, if most of the machines share the same switch, failure of that switch could cause a correlated failure and bring down the service. The same holds true of shared power circuits, cooling systems, etc.</p>
<p><a name="Single+Machine+Requirements"></a></p>
<h4>Single Machine Requirements</h4>
<p>If ZooKeeper has to contend with other applications for access to resources like storage media, CPU, network, or memory, its performance will suffer markedly.  ZooKeeper has strong durability guarantees, which means it uses storage media to log changes before the operation responsible for the change is allowed to complete. You should be aware of this dependency then, and take great care if you want to ensure that ZooKeeper operations aren’t held up by your media. Here are some things you can do to minimize that sort of degradation:</p>
<ul>
<li>ZooKeeper's transaction log must be on a dedicated device. (A dedicated partition is not enough.) ZooKeeper writes the log sequentially, without seeking Sharing your log device with other processes can cause seeks and contention, which in turn can cause multi-second delays.</li>
<li>Do not put ZooKeeper in a situation that can cause a swap. In order for ZooKeeper to function with any sort of timeliness, it simply cannot be allowed to swap. Therefore, make certain that the maximum heap size given to ZooKeeper is not bigger than the amount of real memory available to ZooKeeper.  For more on this, see <a href="#sc_commonProblems">Things to Avoid</a> below.</li>
</ul>
<p><a name="sc_provisioning"></a></p>
<h3>Provisioning</h3>
<p><a name="sc_strengthsAndLimitations"></a></p>
<h3>Things to Consider: ZooKeeper Strengths and Limitations</h3>
<p><a name="sc_administering"></a></p>
<h3>Administering</h3>
<p><a name="sc_maintenance"></a></p>
<h3>Maintenance</h3>
<p>Little long term maintenance is required for a ZooKeeper cluster however you must be aware of the following:</p>
<p><a name="Ongoing+Data+Directory+Cleanup"></a></p>
<h4>Ongoing Data Directory Cleanup</h4>
<p>The ZooKeeper <a href="#var_datadir">Data Directory</a> contains files which are a persistent copy of the znodes stored by a particular serving ensemble. These are the snapshot and transactional log files. As changes are made to the znodes these changes are appended to a transaction log. Occasionally, when a log grows large, a snapshot of the current state of all znodes will be written to the filesystem and a new transaction log file is created for future transactions. During snapshotting, ZooKeeper may continue appending incoming transactions to the old log file. Therefore, some transactions which are newer than a snapshot may be found in the last transaction log preceding the snapshot.</p>
<p>A ZooKeeper server <strong>will not remove old snapshots and log files</strong> when using the default configuration (see autopurge below), this is the responsibility of the operator. Every serving environment is different and therefore the requirements of managing these files may differ from install to install (backup for example).</p>
<p>The PurgeTxnLog utility implements a simple retention policy that administrators can use. The <a href="index.html">API docs</a> contains details on calling conventions (arguments, etc...).</p>
<p>In the following example the last count snapshots and their corresponding logs are retained and the others are deleted.  The value of <count> should typically be greater than 3 (although not required, this provides 3 backups in the unlikely event a recent log has become corrupted). This can be run as a cron job on the ZooKeeper server machines to clean up the logs daily.</p>
<pre><code>java -cp zookeeper.jar:lib/slf4j-api-1.7.5.jar:lib/slf4j-log4j12-1.7.5.jar:lib/log4j-1.2.17.jar:conf org.apache.zookeeper.server.PurgeTxnLog &lt;dataDir&gt; &lt;snapDir&gt; -n &lt;count&gt;
</code></pre>
<p>Automatic purging of the snapshots and corresponding transaction logs was introduced in version 3.4.0 and can be enabled via the following configuration parameters <strong>autopurge.snapRetainCount</strong> and <strong>autopurge.purgeInterval</strong>. For more on this, see <a href="#sc_advancedConfiguration">Advanced Configuration</a> below.</p>
<p><a name="Debug+Log+Cleanup+%28log4j%29"></a></p>
<h4>Debug Log Cleanup (log4j)</h4>
<p>See the section on <a href="#sc_logging">logging</a> in this document. It is expected that you will setup a rolling file appender using the in-built log4j feature. The sample configuration file in the release tar's conf/log4j.properties provides an example of this.</p>
<p><a name="sc_supervision"></a></p>
<h3>Supervision</h3>
<p>You will want to have a supervisory process that manages each of your ZooKeeper server processes (JVM). The ZK server is designed to be &quot;fail fast&quot; meaning that it will shutdown (process exit) if an error occurs that it cannot recover from. As a ZooKeeper serving cluster is highly reliable, this means that while the server may go down the cluster as a whole is still active and serving requests. Additionally, as the cluster is &quot;self healing&quot; the failed server once restarted will automatically rejoin the ensemble w/o any manual interaction.</p>
<p>Having a supervisory process such as <a href="http://cr.yp.to/daemontools.html">daemontools</a> or <a href="http://en.wikipedia.org/wiki/Service_Management_Facility">SMF</a> (other options for supervisory process are also available, it's up to you which one you would like to use, these are just two examples) managing your ZooKeeper server ensures that if the process does exit abnormally it will automatically be restarted and will quickly rejoin the cluster.</p>
<p>It is also recommended to configure the ZooKeeper server process to terminate and dump its heap if an OutOfMemoryError** occurs.  This is achieved by launching the JVM with the following arguments on Linux and Windows respectively.  The <em>zkServer.sh</em> and <em>zkServer.cmd</em> scripts that ship with ZooKeeper set these options.</p>
<pre><code>-XX:+HeapDumpOnOutOfMemoryError -XX:OnOutOfMemoryError='kill -9 %p'

&quot;-XX:+HeapDumpOnOutOfMemoryError&quot; &quot;-XX:OnOutOfMemoryError=cmd /c taskkill /pid %%%%p /t /f&quot;
</code></pre>
<p><a name="sc_monitoring"></a></p>
<h3>Monitoring</h3>
<p>The ZooKeeper service can be monitored in one of three primary ways:</p>
<ul>
<li>the command port through the use of <a href="#sc_zkCommands">4 letter words</a></li>
<li>with <a href="zookeeperJMX.html">JMX</a></li>
<li>using the <code>zkServer.sh status</code> command</li>
</ul>
<p><a name="sc_logging"></a></p>
<h3>Logging</h3>
<p>ZooKeeper uses <strong><a href="http://www.slf4j.org">SLF4J</a></strong> version 1.7.5 as its logging infrastructure. For backward compatibility it is bound to <strong>LOG4J</strong> but you can use <strong><a href="http://logback.qos.ch/">LOGBack</a></strong> or any other supported logging framework of your choice.</p>
<p>The ZooKeeper default <em>log4j.properties</em> file resides in the <em>conf</em> directory. Log4j requires that <em>log4j.properties</em> either be in the working directory (the directory from which ZooKeeper is run) or be accessible from the classpath.</p>
<p>For more information about SLF4J, see <a href="http://www.slf4j.org/manual.html">its manual</a>.</p>
<p>For more information about LOG4J, see <a href="http://logging.apache.org/log4j/1.2/manual.html#defaultInit">Log4j Default Initialization Procedure</a> of the log4j manual.</p>
<p><a name="sc_troubleshooting"></a></p>
<h3>Troubleshooting</h3>
<ul>
<li><em>Server not coming up because of file corruption</em> : A server might not be able to read its database and fail to come up because of some file corruption in the transaction logs of the ZooKeeper server. You will see some IOException on loading ZooKeeper database. In such a case, make sure all the other servers in your ensemble are up and  working. Use &quot;stat&quot; command on the command port to see if they are in good health. After you have verified that all the other servers of the ensemble are up, you can go ahead and clean the database of the corrupt server. Delete all the files in datadir/version-2 and datalogdir/version-2/. Restart the server.</li>
</ul>
<p><a name="sc_configuration"></a></p>
<h3>Configuration Parameters</h3>
<p>ZooKeeper's behavior is governed by the ZooKeeper configuration file. This file is designed so that the exact same file can be used by all the servers that make up a ZooKeeper server assuming the disk layouts are the same. If servers use different configuration files, care must be taken to ensure that the list of servers in all of the different configuration files match.</p>
<h6>Note</h6>
<blockquote>
<p>In 3.5.0 and later, some of these parameters should be placed in a dynamic configuration file. If they are placed in the static configuration file, ZooKeeper will automatically move them over to the dynamic configuration file. See <a href="zookeeperReconfig.html">Dynamic Reconfiguration</a> for more information.</p>
</blockquote>
<p><a name="sc_minimumConfiguration"></a></p>
<h4>Minimum Configuration</h4>
<p>Here are the minimum configuration keywords that must be defined in the configuration file:</p>
<ul>
<li>
<p><em>clientPort</em> : the port to listen for client connections; that is, the port that clients attempt to connect to.</p>
</li>
<li>
<p><em>secureClientPort</em> : the port to listen on for secure client connections using SSL. <strong>clientPort</strong> specifies the port for plaintext connections while <strong>secureClientPort</strong> specifies the port for SSL connections. Specifying both enables mixed-mode while omitting either will disable that mode. Note that SSL feature will be enabled when user plugs-in zookeeper.serverCnxnFactory, zookeeper.clientCnxnSocket as Netty.</p>
</li>
<li>
<p><em>dataDir</em> : the location where ZooKeeper will store the in-memory database snapshots and, unless specified otherwise, the transaction log of updates to the database.</p>
<h6>Note</h6>
<blockquote>
<p>Be careful where you put the transaction log. A dedicated transaction log device is key to consistent good performance. Putting the log on a busy device will adversely effect performance.</p>
</blockquote>
</li>
<li><em>tickTime</em> : the length of a single tick, which is the basic time unit used by ZooKeeper, as measured in milliseconds. It is used to regulate heartbeats, and timeouts. For example, the minimum session timeout will be two ticks.</li>
</ul>
<p><a name="sc_advancedConfiguration"></a></p>
<h4>Advanced Configuration</h4>
<p>The configuration settings in the section are optional. You can use them to further fine tune the behaviour of your ZooKeeper servers. Some can also be set using Java system properties, generally of the form <em>zookeeper.keyword</em>. The exact system property, when available, is noted below.</p>
<ul>
<li><em>dataLogDir</em> : (No Java system property) This option will direct the machine to write the transaction log to the <strong>dataLogDir</strong> rather than the <strong>dataDir</strong>. This allows a dedicated log device to be used, and helps avoid competition between logging and snapshots.
<h6>Note</h6>
<blockquote>
<p>Having a dedicated log device has a large impact on throughput and stable latencies. It is highly recommended to dedicate a log device and set <strong>dataLogDir</strong> to point to a directory on that device, and then make sure to point <strong>dataDir</strong> to a directory <em>not</em> residing on that device.</p>
</blockquote>
</li>
<li><em>globalOutstandingLimit</em> : (Java system property: <strong>zookeeper.globalOutstandingLimit.</strong>) Clients can submit requests faster than ZooKeeper can process them, especially if there are a lot of clients. To prevent ZooKeeper from running out of memory due to queued requests, ZooKeeper will throttle clients so that there is no more than globalOutstandingLimit outstanding requests in the system. The default limit is 1,000.</li>
<li>
<p><em>preAllocSize</em> : (Java system property: <strong>zookeeper.preAllocSize</strong>) To avoid seeks ZooKeeper allocates space in the transaction log file in blocks of preAllocSize kilobytes. The default block size is 64M. One reason for changing the size of the blocks is to reduce the block size if snapshots are taken more often. (Also, see <strong>snapCount</strong>).</p>
</li>
<li>
<p><em>snapCount</em> : (Java system property: <strong>zookeeper.snapCount</strong>) ZooKeeper records its transactions using snapshots and a transaction log (think write-ahead log).The number of transactions recorded in the transaction log before a snapshot can be taken (and the transaction log rolled) is determined by snapCount. In order to prevent all of the machines in the quorum from taking a snapshot at the same time, each ZooKeeper server will take a snapshot when the number of transactions in the transaction log reaches a runtime generated random value in the [snapCount/2+1, snapCount] range.The default snapCount is 100,000.</p>
</li>
<li>
<p><em>maxClientCnxns</em> : (No Java system property) Limits the number of concurrent connections (at the socket level) that a single client, identified by IP address, may make to a single member of the ZooKeeper ensemble. This is used to prevent certain classes of DoS attacks, including file descriptor exhaustion. The default is 60. Setting this to 0 entirely removes the limit on concurrent connections.</p>
</li>
<li>
<p><em>clientPortAddress</em> : <strong>New in 3.3.0:</strong> the address (ipv4, ipv6 or hostname) to listen for client connections; that is, the address that clients attempt to connect to. This is optional, by default we bind in such a way that any connection to the <strong>clientPort</strong> for any address/interface/nic on the server will be accepted.</p>
</li>
<li>
<p><em>minSessionTimeout</em> : (No Java system property) <strong>New in 3.3.0:</strong> the minimum session timeout in milliseconds that the server will allow the client to negotiate. Defaults to 2 times the <strong>tickTime</strong>.</p>
</li>
<li>
<p><em>maxSessionTimeout</em> : (No Java system property) <strong>New in 3.3.0:</strong> the maximum session timeout in milliseconds that the server will allow the client to negotiate. Defaults to 20 times the <strong>tickTime</strong>.</p>
</li>
<li>
<p><em>fsync.warningthresholdms</em> : (Java system property: <strong>zookeeper.fsync.warningthresholdms</strong>) <strong>New in 3.3.4:</strong> A warning message will be output to the log whenever an fsync in the Transactional Log (WAL) takes longer than this value. The values is specified in milliseconds and defaults to 1000. This value can only be set as a system property.</p>
</li>
<li>
<p><em>autopurge.snapRetainCount</em> : (No Java system property) <strong>New in 3.4.0:</strong> When enabled, ZooKeeper auto purge feature retains the <strong>autopurge.snapRetainCount</strong> most recent snapshots and the corresponding transaction logs in the <strong>dataDir</strong> and <strong>dataLogDir</strong> respectively and deletes the rest. Defaults to 3. Minimum value is 3.</p>
</li>
<li>
<p><em>autopurge.purgeInterval</em> : (No Java system property) <strong>New in 3.4.0:</strong> The time interval in hours for which the purge task has to be triggered. Set to a positive integer (1 and above) to enable the auto purging. Defaults to 0.</p>
</li>
<li>
<p><em>syncEnabled</em> : (Java system property: <strong>zookeeper.observer.syncEnabled</strong>) <strong>New in 3.4.6, 3.5.0:</strong> The observers now log transaction and write snapshot to disk by default like the participants. This reduces the recovery time of the observers on restart. Set to &quot;false&quot; to disable this feature. Default is &quot;true&quot;</p>
</li>
<li>
<p><em>zookeeper.extendedTypesEnabled</em> : (Java system property only: <strong>zookeeper.extendedTypesEnabled</strong>) <strong>New in 3.5.4:</strong> Define to &quot;true&quot; to enable extended features such as the creation of TTL Nodes. They are disabled by default. IMPORTANT: when enabled server IDs must be less than 255 due to internal limitations.</p>
</li>
<li>
<p><em>zookeeper.emulate353TTLNodes</em> : (Java system property only: <strong>zookeeper.emulate353TTLNodes</strong>) <strong>New in 3.5.4:</strong> Due to ZOOKEEPER-2901 TTL nodes created in version 3.5.3 are not supported in 3.5.4/3.6.0. However, a workaround is provided via the zookeeper.emulate353TTLNodes system property. If you used TTL nodes in ZooKeeper 3.5.3 and need to maintain compatibility set <strong>zookeeper.emulate353TTLNodes</strong> to &quot;true&quot; in addition to <strong>zookeeper.extendedTypesEnabled</strong>. NOTE: due to the bug, server IDs must be 127 or less. Additionally, the maximum support TTL value is 1099511627775 which is smaller than what was allowed in 3.5.3 (1152921504606846975)</p>
</li>
<li>
<p><em>serverCnxnFactory</em> : (Java system property: <strong>zookeeper.serverCnxnFactory</strong>) Specifies ServerCnxnFactory implementation. This should be set to <code>NettyServerCnxnFactory</code> in order to use TLS based server communication. Default is <code>NIOServerCnxnFactory</code>.</p>
</li>
<li>
<p><em>snapshot.trust.empty</em> : (Java system property: <strong>zookeeper.snapshot.trust.empty</strong>) <strong>New in 3.5.6:</strong> This property controls whether or not ZooKeeper should treat missing snapshot files as a fatal state that can't be recovered from. Set to true to allow ZooKeeper servers recover without snapshot files. This should only be set during upgrading from old versions of ZooKeeper (3.4.x, pre 3.5.3) where ZooKeeper might only have transaction log files but without presence of snapshot files. If the value is set during upgrade, we recommend to set the value back to false after upgrading and restart ZooKeeper process so ZooKeeper can continue normal data consistency check during recovery process. Default value is false.</p>
</li>
</ul>
<p><a name="sc_clusterOptions"></a></p>
<h4>Cluster Options</h4>
<p>The options in this section are designed for use with an ensemble of servers -- that is, when deploying clusters of servers.</p>
<ul>
<li><em>electionAlg</em> : (No Java system property) Election implementation to use. A value of &quot;1&quot; corresponds to the non-authenticated UDP-based version of fast leader election, &quot;2&quot; corresponds to the authenticated UDP-based version of fast leader election, and &quot;3&quot; corresponds to TCP-based version of fast leader election. Currently, algorithm 3 is the default.
<h6>Note</h6>
<blockquote>
<p>The implementations of leader election 1, and 2 are now <strong>deprecated</strong>. We have the intention of removing them in the next release, at which point only the FastLeaderElection will be available.</p>
</blockquote>
</li>
<li><em>initLimit</em> : (No Java system property) Amount of time, in ticks (see <a href="#id_tickTime">tickTime</a>), to allow followers to connect and sync to a leader. Increased this value as needed, if the amount of data managed by ZooKeeper is large.</li>
<li>
<p><em>leaderServes</em> : (Java system property: zookeeper.<strong>leaderServes</strong>) Leader accepts client connections. Default value is &quot;yes&quot;. The leader machine coordinates updates. For higher update throughput at the slight expense of read throughput the leader can be configured to not accept clients and focus on coordination. The default to this option is yes, which means that a leader will accept client connections.</p>
<h6>Note</h6>
<blockquote>
<p>Turning on leader selection is highly recommended when you have more than three ZooKeeper servers in an ensemble.</p>
</blockquote>
</li>
<li><em>server.x=[hostname]:nnnnn[:nnnnn], etc</em> : (No Java system property) servers making up the ZooKeeper ensemble. When the server starts up, it determines which server it is by looking for the file <em>myid</em> in the data directory. That file contains the server number, in ASCII, and it should match <strong>x</strong> in <strong>server.x</strong> in the left hand side of this setting. The list of servers that make up ZooKeeper servers that is used by the clients must match the list of ZooKeeper servers that each ZooKeeper server has. There are two port numbers <strong>nnnnn</strong>. The first followers use to connect to the leader, and the second is for leader election. If you want to test multiple servers on a single machine, then different ports can be used for each server.</li>
<li>
<p><em>syncLimit</em> : (No Java system property) Amount of time, in ticks (see <a href="#id_tickTime">tickTime</a>), to allow followers to sync with ZooKeeper. If followers fall too far behind a leader, they will be dropped.</p>
</li>
<li>
<p><em>group.x=nnnnn[:nnnnn]</em> : (No Java system property) Enables a hierarchical quorum construction.&quot;x&quot; is a group identifier and the numbers following the &quot;=&quot; sign correspond to server identifiers. The left-hand side of the assignment is a colon-separated list of server identifiers. Note that groups must be disjoint and the union of all groups must be the ZooKeeper ensemble. You will find an example <a href="zookeeperHierarchicalQuorums.html">here</a></p>
</li>
<li>
<p><em>weight.x=nnnnn</em> : (No Java system property) Used along with &quot;group&quot;, it assigns a weight to a server when forming quorums. Such a value corresponds to the weight of a server when voting. There are a few parts of ZooKeeper that require voting such as leader election and the atomic broadcast protocol. By default the weight of server is 1. If the configuration defines groups, but not weights, then a value of 1 will be assigned to all servers. You will find an example <a href="zookeeperHierarchicalQuorums.html">here</a></p>
</li>
<li>
<p><em>cnxTimeout</em> : (Java system property: zookeeper.<strong>cnxTimeout</strong>) Sets the timeout value for opening connections for leader election notifications. Only applicable if you are using electionAlg 3.</p>
<h6>Note</h6>
<blockquote>
<p>Default value is 5 seconds.</p>
</blockquote>
</li>
<li><em>standaloneEnabled</em> : (No Java system property) <strong>New in 3.5.0:</strong> When set to false, a single server can be started in replicated mode, a lone participant can run with observers, and a cluster can reconfigure down to one node, and up from one node. The default is true for backwards compatibility. It can be set using QuorumPeerConfig's setStandaloneEnabled method or by adding &quot;standaloneEnabled=false&quot; or &quot;standaloneEnabled=true&quot; to a server's config file.</li>
<li>
<p><em>reconfigEnabled</em> : (No Java system property) <strong>New in 3.5.3:</strong> This controls the enabling or disabling of <a href="zookeeperReconfig.html">Dynamic Reconfiguration</a> feature. When the feature is enabled, users can perform reconfigure operations through the ZooKeeper client API or through ZooKeeper command line tools assuming users are authorized to perform such operations. When the feature is disabled, no user, including the super user, can perform a reconfiguration. Any attempt to reconfigure will return an error. <strong>&quot;reconfigEnabled&quot;</strong> option can be set as <strong>&quot;reconfigEnabled=false&quot;</strong> or <strong>&quot;reconfigEnabled=true&quot;</strong> to a server's config file, or using QuorumPeerConfig's setReconfigEnabled method. The default value is false. If present, the value should be consistent across every server in the entire ensemble. Setting the value as true on some servers and false on other servers will cause inconsistent behavior depending on which server is elected as leader. If the leader has a setting of <strong>&quot;reconfigEnabled=true&quot;</strong>, then the ensemble will have reconfig feature enabled. If the leader has a setting of <strong>&quot;reconfigEnabled=false&quot;</strong>, then the ensemble will have reconfig feature disabled. It is thus recommended to have a consistent value for <strong>&quot;reconfigEnabled&quot;</strong> across servers in the ensemble.</p>
</li>
<li>
<p><em>4lw.commands.whitelist</em> : (Java system property: <strong>zookeeper.4lw.commands.whitelist</strong>) <strong>New in 3.5.3:</strong> A list of comma separated <a href="#sc_4lw">Four Letter Words</a> commands that user wants to use. A valid Four Letter Words command must be put in this list else ZooKeeper server will not enable the command. By default the whitelist only contains &quot;srvr&quot; command which zkServer.sh uses. The rest of four letter word commands are disabled by default. Here's an example of the configuration that enables stat, ruok, conf, and isro command while disabling the rest of Four Letter Words command:</p>
<pre><code>4lw.commands.whitelist=stat, ruok, conf, isro
</code></pre>
</li>
</ul>
<p>If you really need enable all four letter word commands by default, you can use the asterisk option so you don't have to include every command one by one in the list. As an example, this will enable all four letter word commands:</p>
<pre><code>4lw.commands.whitelist=*
</code></pre>
<ul>
<li>
<p><em>tcpKeepAlive</em> : (Java system property: <strong>zookeeper.tcpKeepAlive</strong>) <strong>New in 3.5.4:</strong> Setting this to true sets the TCP keepAlive flag on the sockets used by quorum members to perform elections. This will allow for connections between quorum members to remain up when there is network infrastructure that may otherwise break them. Some NATs and firewalls may terminate or lose state for long running or idle connections. Enabling this option relies on OS level settings to work properly, check your operating system's options regarding TCP keepalive for more information.  Defaults to <strong>false</strong>.</p>
</li>
<li>
<p><em>electionPortBindRetry</em> : (Java system property only: <strong>zookeeper.electionPortBindRetry</strong>) Property set max retry count when Zookeeper server fails to bind leader election port. Such errors can be temporary and recoverable, such as DNS issue described in <a href="https://issues.apache.org/jira/projects/ZOOKEEPER/issues/ZOOKEEPER-3320">ZOOKEEPER-3320</a>, or non-retryable, such as port already in use.<br />
In case of transient errors, this property can improve availability of Zookeeper server and help it to self recover. Default value 3. In container environment, especially in Kubernetes, this value should be increased or set to 0(infinite retry) to overcome issues related to DNS name resolving.</p>
</li>
</ul>
<p><a name="sc_authOptions"></a></p>
<h4>Encryption, Authentication, Authorization Options</h4>
<p>The options in this section allow control over encryption/authentication/authorization performed by the service.</p>
<p>Beside this page, you can also find useful information about client side configuration in the <a href="zookeeperProgrammers.html#sc_java_client_configuration">Programmers Guide</a>. The ZooKeeper Wiki also has useful pages about <a href="https://cwiki.apache.org/confluence/display/ZOOKEEPER/ZooKeeper+SSL+User+Guide">ZooKeeper SSL support</a>, and <a href="https://cwiki.apache.org/confluence/display/ZOOKEEPER/ZooKeeper+and+SASL">SASL authentication for ZooKeeper</a>.</p>
<ul>
<li>
<p><em>DigestAuthenticationProvider.superDigest</em> : (Java system property: <strong>zookeeper.DigestAuthenticationProvider.superDigest</strong>) By default this feature is <strong>disabled</strong> <strong>New in 3.2:</strong> Enables a ZooKeeper ensemble administrator to access the znode hierarchy as a &quot;super&quot; user. In particular no ACL checking occurs for a user authenticated as super. org.apache.zookeeper.server.auth.DigestAuthenticationProvider can be used to generate the superDigest, call it with one parameter of &quot;super:<password>&quot;. Provide the generated &quot;super:<data>&quot; as the system property value when starting each server of the ensemble. When authenticating to a ZooKeeper server (from a ZooKeeper client) pass a scheme of &quot;digest&quot; and authdata of &quot;super:<password>&quot;. Note that digest auth passes the authdata in plaintext to the server, it would be prudent to use this authentication method only on localhost (not over the network) or over an encrypted connection.</p>
</li>
<li>
<p><em>X509AuthenticationProvider.superUser</em> : (Java system property: <strong>zookeeper.X509AuthenticationProvider.superUser</strong>) The SSL-backed way to enable a ZooKeeper ensemble administrator to access the znode hierarchy as a &quot;super&quot; user. When this parameter is set to an X500 principal name, only an authenticated client with that principal will be able to bypass ACL checking and have full privileges to all znodes.</p>
</li>
<li>
<p><em>zookeeper.superUser</em> : (Java system property: <strong>zookeeper.superUser</strong>) Similar to <strong>zookeeper.X509AuthenticationProvider.superUser</strong> but is generic for SASL based logins. It stores the name of a user that can access the znode hierarchy as a &quot;super&quot; user.</p>
</li>
<li>
<p><em>ssl.authProvider</em> : (Java system property: <strong>zookeeper.ssl.authProvider</strong>) Specifies a subclass of <strong>org.apache.zookeeper.auth.X509AuthenticationProvider</strong> to use for secure client authentication. This is useful in certificate key infrastructures that do not use JKS. It may be necessary to extend <strong>javax.net.ssl.X509KeyManager</strong> and <strong>javax.net.ssl.X509TrustManager</strong> to get the desired behavior from the SSL stack. To configure the ZooKeeper server to use the custom provider for authentication, choose a scheme name for the custom AuthenticationProvider and set the property <strong>zookeeper.authProvider.[scheme]</strong> to the fully-qualified class name of the custom implementation. This will load the provider into the ProviderRegistry. Then set this property <strong>zookeeper.ssl.authProvider=[scheme]</strong> and that provider will be used for secure authentication.</p>
</li>
<li>
<p><em>zookeeper.sessionRequireClientSASLAuth</em> : (Java system property only: <strong>zookeeper.sessionRequireClientSASLAuth</strong>) <strong>New in 3.5.9:</strong> When set to <strong>true</strong>, ZooKeeper server will only accept connections and requests from clients that have authenticated with server via SASL. Clients that are not configured with SASL authentication, or configured with SASL but failed authentication (i.e. with invalid credential) will not be able to establish a session with server. A typed error code (-124) will be delivered in such case, both Java and C client will close the session with server thereafter, without further attempts on retrying to reconnect.</p>
<p>By default, this feature is disabled. Users who would like to opt-in can enable the feature by setting <strong>zookeeper.sessionRequireClientSASLAuth</strong> to <strong>true</strong>.</p>
<p>This feature overrules the <emphasis role="bold">zookeeper.allowSaslFailedClients</emphasis> option, so even if server is configured to allow clients that fail SASL authentication to login, client will not be able to establish a session with server if this feature is enabled.</p>
</li>
<li>
<p><em>sslQuorum</em> : (Java system property: <strong>zookeeper.sslQuorum</strong>) <strong>New in 3.5.5:</strong> Enables encrypted quorum communication. Default is <code>false</code>.</p>
</li>
<li>
<p><em>ssl.keyStore.location and ssl.keyStore.password</em> and <em>ssl.quorum.keyStore.location</em> and <em>ssl.quorum.keyStore.password</em> : (Java system properties: <strong>zookeeper.ssl.keyStore.location</strong> and <strong>zookeeper.ssl.keyStore.password</strong> and <strong>zookeeper.ssl.quorum.keyStore.location</strong> and <strong>zookeeper.ssl.quorum.keyStore.password</strong>) <strong>New in 3.5.5:</strong> Specifies the file path to a Java keystore containing the local credentials to be used for client and quorum TLS connections, and the password to unlock the file.</p>
</li>
<li>
<p><em>ssl.keyStore.type</em> and <em>ssl.quorum.keyStore.type</em> : (Java system properties: <strong>zookeeper.ssl.keyStore.type</strong> and <strong>zookeeper.ssl.quorum.keyStore.type</strong>) <strong>New in 3.5.5:</strong> Specifies the file format of client and quorum keystores. Values: JKS, PEM, PKCS12 or null (detect by filename).<br />
Default: null</p>
</li>
<li>
<p><em>ssl.trustStore.location</em> and <em>ssl.trustStore.password</em> and <em>ssl.quorum.trustStore.location</em> and <em>ssl.quorum.trustStore.password</em> : (Java system properties: <strong>zookeeper.ssl.trustStore.location</strong> and <strong>zookeeper.ssl.trustStore.password</strong> and <strong>zookeeper.ssl.quorum.trustStore.location</strong> and <strong>zookeeper.ssl.quorum.trustStore.password</strong>) <strong>New in 3.5.5:</strong> Specifies the file path to a Java truststore containing the remote credentials to be used for client and quorum TLS connections, and the password to unlock the file.</p>
</li>
<li>
<p><em>ssl.trustStore.type</em> and <em>ssl.quorum.trustStore.type</em> : (Java system properties: <strong>zookeeper.ssl.trustStore.type</strong> and <strong>zookeeper.ssl.quorum.trustStore.type</strong>) <strong>New in 3.5.5:</strong> Specifies the file format of client and quorum trustStores. Values: JKS, PEM, PKCS12 or null (detect by filename).<br />
Default: null</p>
</li>
<li>
<p><em>ssl.protocol</em> and <em>ssl.quorum.protocol</em> : (Java system properties: <strong>zookeeper.ssl.protocol</strong> and <strong>zookeeper.ssl.quorum.protocol</strong>) <strong>New in 3.5.5:</strong> Specifies to protocol to be used in client and quorum TLS negotiation. Default: TLSv1.2</p>
</li>
<li>
<p><em>ssl.enabledProtocols</em> and <em>ssl.quorum.enabledProtocols</em> : (Java system properties: <strong>zookeeper.ssl.enabledProtocols</strong> and <strong>zookeeper.ssl.quorum.enabledProtocols</strong>) <strong>New in 3.5.5:</strong> Specifies the enabled protocols in client and quorum TLS negotiation. Default: value of <code>protocol</code> property</p>
</li>
<li>
<p><em>ssl.ciphersuites</em> and <em>ssl.quorum.ciphersuites</em> : (Java system properties: <strong>zookeeper.ssl.ciphersuites</strong> and <strong>zookeeper.ssl.quorum.ciphersuites</strong>) <strong>New in 3.5.5:</strong> Specifies the enabled cipher suites to be used in client and quorum TLS negotiation. Default: Enabled cipher suites depend on the Java runtime version being used.</p>
</li>
<li>
<p><em>ssl.context.supplier.class</em> and <em>ssl.quorum.context.supplier.class</em> : (Java system properties: <strong>zookeeper.ssl.context.supplier.class</strong> and <strong>zookeeper.ssl.quorum.context.supplier.class</strong>) <strong>New in 3.5.5:</strong> Specifies the class to be used for creating SSL context in client and quorum SSL communication. This allows you to use custom SSL context and implement the following scenarios:</p>
<ol>
<li>Use hardware keystore, loaded in using PKCS11 or something similar.</li>
<li>You don't have access to the software keystore, but can retrieve an already-constructed SSLContext from their container. Default: null</li>
</ol>
</li>
<li>
<p><em>ssl.hostnameVerification</em> and <em>ssl.quorum.hostnameVerification</em> : (Java system properties: <strong>zookeeper.ssl.hostnameVerification</strong> and <strong>zookeeper.ssl.quorum.hostnameVerification</strong>) <strong>New in 3.5.5:</strong> Specifies whether the hostname verification is enabled in client and quorum TLS negotiation process. Disabling it only recommended for testing purposes. Default: true</p>
</li>
<li>
<p><em>ssl.crl</em> and <em>ssl.quorum.crl</em> : (Java system properties: <strong>zookeeper.ssl.crl</strong> and <strong>zookeeper.ssl.quorum.crl</strong>) <strong>New in 3.5.5:</strong> Specifies whether Certificate Revocation List is enabled in client and quorum TLS protocols. Default: false</p>
</li>
<li>
<p><em>ssl.ocsp</em> and <em>ssl.quorum.ocsp</em> : (Java system properties: <strong>zookeeper.ssl.ocsp</strong> and <strong>zookeeper.ssl.quorum.ocsp</strong>) <strong>New in 3.5.5:</strong> Specifies whether Online Certificate Status Protocol is enabled in client and quorum TLS protocols. Default: false</p>
</li>
<li>
<p><em>ssl.clientAuth</em> and <em>ssl.quorum.clientAuth</em> : (Java system properties: <strong>zookeeper.ssl.clientAuth</strong> and <strong>zookeeper.ssl.quorum.clientAuth</strong>) <strong>Added in 3.5.5, but broken until 3.5.7:</strong> Specifies options to authenticate ssl connections from clients. Valid values are</p>
<ul>
<li>&quot;none&quot;: server will not request client authentication</li>
<li>&quot;want&quot;: server will &quot;request&quot; client authentication</li>
<li>&quot;need&quot;: server will &quot;require&quot; client authentication</li>
</ul>
<p>Default: &quot;need&quot;</p>
</li>
<li>
<p><em>ssl.handshakeDetectionTimeoutMillis</em> and <em>ssl.quorum.handshakeDetectionTimeoutMillis</em> : (Java system properties: <strong>zookeeper.ssl.handshakeDetectionTimeoutMillis</strong> and <strong>zookeeper.ssl.quorum.handshakeDetectionTimeoutMillis</strong>) <strong>New in 3.5.5:</strong> TBD</p>
</li>
<li>
<p><em>client.portUnification</em>: (Java system property: <strong>zookeeper.client.portUnification</strong>) <strong>New in 3.5.7</strong> Specifies that the client port should accept SSL connections (using the same configuration as the secure client port). Default: false</p>
</li>
<li>
<p><em>authProvider</em>: (Java system property: <strong>zookeeper.authProvider</strong>) You can specify multiple authentication provider classes for ZooKeeper. Usually you use this parameter to specify the SASL authentication provider like: <code>authProvider.1=org.apache.zookeeper.server.auth.SASLAuthenticationProvider</code></p>
</li>
<li>
<p><em>kerberos.removeHostFromPrincipal</em> (Java system property: <strong>zookeeper.kerberos.removeHostFromPrincipal</strong>) You can instruct ZooKeeper to remove the host from the client principal name during authentication. (e.g. the zk/myhost@EXAMPLE.COM client principal will be authenticated in ZooKeeper as zk@EXAMPLE.COM) Default: false</p>
</li>
<li>
<p><em>kerberos.removeRealmFromPrincipal</em> (Java system property: <strong>zookeeper.kerberos.removeRealmFromPrincipal</strong>) You can instruct ZooKeeper to remove the realm from the client principal name during authentication. (e.g. the zk/myhost@EXAMPLE.COM client principal will be authenticated in ZooKeeper as zk/myhost) Default: false</p>
</li>
</ul>
<p><a name="Experimental+Options%2FFeatures"></a></p>
<h4>Experimental Options/Features</h4>
<p>New features that are currently considered experimental.</p>
<ul>
<li><em>Read Only Mode Server</em> : (Java system property: <strong>readonlymode.enabled</strong>) <strong>New in 3.4.0:</strong> Setting this value to true enables Read Only Mode server support (disabled by default). ROM allows clients sessions which requested ROM support to connect to the server even when the server might be partitioned from the quorum. In this mode ROM clients can still read values from the ZK service, but will be unable to write values and see changes from other clients. See ZOOKEEPER-784 for more details.</li>
</ul>
<p><a name="Unsafe+Options"></a></p>
<h4>Unsafe Options</h4>
<p>The following options can be useful, but be careful when you use them. The risk of each is explained along with the explanation of what the variable does.</p>
<ul>
<li>
<p><em>forceSync</em> : (Java system property: <strong>zookeeper.forceSync</strong>) Requires updates to be synced to media of the transaction log before finishing processing the update. If this option is set to no, ZooKeeper will not require updates to be synced to the media.</p>
</li>
<li>
<p><em>jute.maxbuffer:</em> : (Java system property:<strong>jute.maxbuffer</strong>) This option can only be set as a Java system property. There is no zookeeper prefix on it. It specifies the maximum size of the data that can be stored in a znode. The default is 0xfffff, or just under 1M. If this option is changed, the system property must be set on all servers and clients otherwise problems will arise. This is really a sanity check. ZooKeeper is designed to store data on the order of kilobytes in size.</p>
</li>
<li>
<p><em>jute.maxbuffer.extrasize</em>: (Java system property: <strong>zookeeper.jute.maxbuffer.extrasize</strong>) <strong>New in 3.5.7:</strong> While processing client requests ZooKeeper server adds some additional information into the requests before persisting it as a transaction. Earlier this additional information size was fixed to 1024 bytes. For many scenarios, specially scenarios where jute.maxbuffer value is more than 1 MB and request type is multi, this fixed size was insufficient. To handle all the scenarios additional information size is increased from 1024 byte to same as jute.maxbuffer size and also it is made configurable through jute.maxbuffer.extrasize. Generally this property is not required to be configured as default value is the most optimal value.</p>
</li>
<li>
<p><em>skipACL</em> : (Java system property: <strong>zookeeper.skipACL</strong>) Skips ACL checks. This results in a boost in throughput, but opens up full access to the data tree to everyone.</p>
</li>
<li>
<p><em>quorumListenOnAllIPs</em> : When set to true the ZooKeeper server will listen for connections from its peers on all available IP addresses, and not only the address configured in the server list of the configuration file. It affects the connections handling the ZAB protocol and the Fast Leader Election protocol. Default value is <strong>false</strong>.</p>
</li>
</ul>
<p><a name="Disabling+data+directory+autocreation"></a></p>
<h4>Disabling data directory autocreation</h4>
<p><strong>New in 3.5:</strong> The default behavior of a ZooKeeper server is to automatically create the data directory (specified in the configuration file) when started if that directory does not already exist. This can be inconvenient and even dangerous in some cases. Take the case where a configuration change is made to a running server, wherein the <strong>dataDir</strong> parameter is accidentally changed. When the ZooKeeper server is restarted it will create this non-existent directory and begin serving - with an empty znode namespace. This scenario can result in an effective &quot;split brain&quot; situation (i.e. data in both the new invalid directory and the original valid data store). As such is would be good to have an option to turn off this autocreate behavior. In general for production environments this should be done, unfortunately however the default legacy behavior cannot be changed at this point and therefore this must be done on a case by case basis. This is left to users and to packagers of ZooKeeper distributions.</p>
<p>When running <strong>zkServer.sh</strong> autocreate can be disabled by setting the environment variable <strong>ZOO_DATADIR_AUTOCREATE_DISABLE</strong> to 1. When running ZooKeeper servers directly from class files this can be accomplished by setting <strong>zookeeper.datadir.autocreate=false</strong> on the java command line, i.e. <strong>-Dzookeeper.datadir.autocreate=false</strong></p>
<p>When this feature is disabled, and the ZooKeeper server determines that the required directories do not exist it will generate an error and refuse to start.</p>
<p>A new script <strong>zkServer-initialize.sh</strong> is provided to support this new feature. If autocreate is disabled it is necessary for the user to first install ZooKeeper, then create the data directory (and potentially txnlog directory), and then start the server. Otherwise as mentioned in the previous paragraph the server will not start. Running <strong>zkServer-initialize.sh</strong> will create the required directories, and optionally setup the myid file (optional command line parameter). This script can be used even if the autocreate feature itself is not used, and will likely be of use to users as this (setup, including creation of the myid file) has been an issue for users in the past. Note that this script ensures the data directories exist only, it does not create a config file, but rather requires a config file to be available in order to execute.</p>
<p><a name="sc_performance_options"></a></p>
<h4>Performance Tuning Options</h4>
<p><strong>New in 3.5.0:</strong> Several subsystems have been reworked to improve read throughput. This includes multi-threading of the NIO communication subsystem and request processing pipeline (Commit Processor). NIO is the default client/server communication subsystem. Its threading model comprises 1 acceptor thread, 1-N selector threads and 0-M socket I/O worker threads. In the request processing pipeline the system can be configured to process multiple read request at once while maintaining the same consistency guarantee (same-session read-after-write). The Commit Processor threading model comprises 1 main thread and 0-N worker threads.</p>
<p>The default values are aimed at maximizing read throughput on a dedicated ZooKeeper machine. Both subsystems need to have sufficient amount of threads to achieve peak read throughput.</p>
<ul>
<li>
<p><em>zookeeper.nio.numSelectorThreads</em> : (Java system property only: <strong>zookeeper.nio.numSelectorThreads</strong>) <strong>New in 3.5.0:</strong> Number of NIO selector threads. At least 1 selector thread required. It is recommended to use more than one selector for large numbers of client connections. The default value is sqrt( number of cpu cores / 2 ).</p>
</li>
<li>
<p><em>zookeeper.nio.numWorkerThreads</em> : (Java system property only: <strong>zookeeper.nio.numWorkerThreads</strong>) <strong>New in 3.5.0:</strong> Number of NIO worker threads. If configured with 0 worker threads, the selector threads do the socket I/O directly. The default value is 2 times the number of cpu cores.</p>
</li>
<li>
<p><em>zookeeper.commitProcessor.numWorkerThreads</em> : (Java system property only: <strong>zookeeper.commitProcessor.numWorkerThreads</strong>) <strong>New in 3.5.0:</strong> Number of Commit Processor worker threads. If configured with 0 worker threads, the main thread will process the request directly. The default value is the number of cpu cores.</p>
</li>
<li>
<p><em>znode.container.checkIntervalMs</em> : (Java system property only) <strong>New in 3.5.1:</strong> The time interval in milliseconds for each check of candidate container and ttl nodes. Default is &quot;60000&quot;.</p>
</li>
<li>
<p><em>znode.container.maxPerMinute</em> : (Java system property only) <strong>New in 3.5.1:</strong> The maximum number of container and ttl nodes that can be deleted per minute. This prevents herding during container deletion. Default is &quot;10000&quot;.</p>
</li>
</ul>
<p><a name="sc_adminserver_config"></a></p>
<h4>AdminServer configuration</h4>
<p><strong>New in 3.5.0:</strong> The following options are used to configure the <a href="#sc_adminserver">AdminServer</a>.</p>
<ul>
<li>
<p><em>admin.enableServer</em> : (Java system property: <strong>zookeeper.admin.enableServer</strong>) Set to &quot;false&quot; to disable the AdminServer.  By default the AdminServer is enabled.</p>
</li>
<li>
<p><em>admin.serverAddress</em> : (Java system property: <strong>zookeeper.admin.serverAddress</strong>) The address the embedded Jetty server listens on. Defaults to 0.0.0.0.</p>
</li>
<li>
<p><em>admin.serverPort</em> : (Java system property: <strong>zookeeper.admin.serverPort</strong>) The port the embedded Jetty server listens on.  Defaults to 8080.</p>
</li>
<li>
<p><em>admin.idleTimeout</em> : (Java system property: <strong>zookeeper.admin.idleTimeout</strong>) Set the maximum idle time in milliseconds that a connection can wait before sending or receiving data. Defaults to 30000 ms.</p>
</li>
<li>
<p><em>admin.commandURL</em> : (Java system property: <strong>zookeeper.admin.commandURL</strong>) The URL for listing and issuing commands relative to the root URL.  Defaults to &quot;/commands&quot;.</p>
</li>
</ul>
<p><a name="Communication+using+the+Netty+framework"></a></p>
<h3>Communication using the Netty framework</h3>
<p><a href="http://netty.io">Netty</a> is an NIO based client/server communication framework, it simplifies (over NIO being used directly) many of the complexities of network level communication for java applications. Additionally the Netty framework has built in support for encryption (SSL) and authentication (certificates). These are optional features and can be turned on or off individually.</p>
<p>In versions 3.5+, a ZooKeeper server can use Netty instead of NIO (default option) by setting the environment variable <strong>zookeeper.serverCnxnFactory</strong> to <strong>org.apache.zookeeper.server.NettyServerCnxnFactory</strong>; for the client, set <strong>zookeeper.clientCnxnSocket</strong> to <strong>org.apache.zookeeper.ClientCnxnSocketNetty</strong>.</p>
<p><a name="Quorum+TLS"></a></p>
<h4>Quorum TLS</h4>
<p><em>New in 3.5.5</em></p>
<p>Based on the Netty Framework ZooKeeper ensembles can be set up to use TLS encryption in their communication channels. This section describes how to set up encryption on the quorum communication.</p>
<p>Please note that Quorum TLS encapsulates securing both leader election and quorum communication protocols.</p>
<ol>
<li>Create SSL keystore JKS to store local credentials</li>
</ol>
<p>One keystore should be created for each ZK instance.</p>
<p>In this example we generate a self-signed certificate and store it together with the private key in <code>keystore.jks</code>. This is suitable for testing purposes, but you probably need an official certificate to sign your keys in a production environment.</p>
<p>Please note that the alias (<code>-alias</code>) and the distinguished name (<code>-dname</code>) must match the hostname of the machine that is associated with, otherwise hostname verification won't work.</p>
<p><code>keytool -genkeypair -alias $(hostname -f) -keyalg RSA -keysize 2048 -dname &quot;cn=$(hostname -f)&quot; -keypass password -keystore keystore.jks -storepass password</code></p>
<ol>
<li>Extract the signed public key (certificate) from keystore</li>
</ol>
<p><em>This step might only necessary for self-signed certificates.</em></p>
<p><code>keytool -exportcert -alias $(hostname -f) -keystore keystore.jks -file $(hostname -f).cer -rfc</code></p>
<ol>
<li>Create SSL truststore JKS containing certificates of all ZooKeeper instances</li>
</ol>
<p>The same truststore (storing all accepted certs) should be shared on participants of the ensemble. You need to use different aliases to store multiple certificates in the same truststore. Name of the aliases doesn't matter.</p>
<p><code>keytool -importcert -alias [host1..3] -file [host1..3].cer -keystore truststore.jks -storepass password</code></p>
<ol>
<li>You need to use <code>NettyServerCnxnFactory</code> as serverCnxnFactory, because SSL is not supported by NIO. Add the following configuration settings to your <code>zoo.cfg</code> config file:</li>
</ol>
<p><code>sslQuorum=true serverCnxnFactory=org.apache.zookeeper.server.NettyServerCnxnFactory ssl.quorum.keyStore.location=/path/to/keystore.jks ssl.quorum.keyStore.password=password ssl.quorum.trustStore.location=/path/to/truststore.jks ssl.quorum.trustStore.password=password</code></p>
<ol>
<li>Verify in the logs that your ensemble is running on TLS:</li>
</ol>
<p><code>INFO [main:QuorumPeer@1789] - Using TLS encrypted quorum communication INFO [main:QuorumPeer@1797] - Port unification disabled ... INFO [QuorumPeerListener:QuorumCnxManager$Listener@877] - Creating TLS-only quorum server socket</code></p>
<p><a name="Upgrading+existing+nonTLS+cluster"></a></p>
<h4>Upgrading existing non-TLS cluster with no downtime</h4>
<p><em>New in 3.5.5</em></p>
<p>Here are the steps needed to upgrade an already running ZooKeeper ensemble to TLS without downtime by taking advantage of port unification functionality.</p>
<ol>
<li>
<p>Create the necessary keystores and truststores for all ZK participants as described in the previous section</p>
</li>
<li>
<p>Add the following config settings and restart the first node</p>
</li>
</ol>
<p><code>sslQuorum=false portUnification=true serverCnxnFactory=org.apache.zookeeper.server.NettyServerCnxnFactory ssl.quorum.keyStore.location=/path/to/keystore.jks ssl.quorum.keyStore.password=password ssl.quorum.trustStore.location=/path/to/truststore.jks ssl.quorum.trustStore.password=password</code></p>
<p>Note that TLS is not yet enabled, but we turn on port unification.</p>
<ol>
<li>Repeat step #2 on the remaining nodes. Verify that you see the following entries in the logs:</li>
</ol>
<p><code>INFO [main:QuorumPeer@1791] - Using insecure (non-TLS) quorum communication INFO [main:QuorumPeer@1797] - Port unification enabled ... INFO [QuorumPeerListener:QuorumCnxManager$Listener@874] - Creating TLS-enabled quorum server socket</code></p>
<p>You should also double check after each node restart that the quorum become healthy again.</p>
<ol>
<li>Enable Quorum TLS on each node and do rolling restart:</li>
</ol>
<p><code>sslQuorum=true portUnification=true</code></p>
<ol>
<li>Once you verified that your entire ensemble is running on TLS, you could disable port unification and do another rolling restart</li>
</ol>
<p><code>sslQuorum=true portUnification=false</code></p>
<p><a name="sc_zkCommands"></a></p>
<h3>ZooKeeper Commands</h3>
<p><a name="sc_4lw"></a></p>
<h4>The Four Letter Words</h4>
<p>ZooKeeper responds to a small set of commands. Each command is composed of four letters. You issue the commands to ZooKeeper via telnet or nc, at the client port.</p>
<p>Three of the more interesting commands: &quot;stat&quot; gives some general information about the server and connected clients, while &quot;srvr&quot; and &quot;cons&quot; give extended details on server and connections respectively.</p>
<p><strong>New in 3.5.3:</strong> Four Letter Words need to be explicitly white listed before using. Please refer <strong>4lw.commands.whitelist</strong> described in <a href="#sc_clusterOptions">cluster configuration section</a> for details. Moving forward, Four Letter Words will be deprecated, please use <a href="#sc_adminserver">AdminServer</a> instead.</p>
<ul>
<li>
<p><em>conf</em> : <strong>New in 3.3.0:</strong> Print details about serving configuration.</p>
</li>
<li>
<p><em>cons</em> : <strong>New in 3.3.0:</strong> List full connection/session details for all clients connected to this server. Includes information on numbers of packets received/sent, session id, operation latencies, last operation performed, etc...</p>
</li>
<li>
<p><em>crst</em> : <strong>New in 3.3.0:</strong> Reset connection/session statistics for all connections.</p>
</li>
<li>
<p><em>dump</em> : Lists the outstanding sessions and ephemeral nodes. This only works on the leader.</p>
</li>
<li>
<p><em>envi</em> : Print details about serving environment</p>
</li>
<li>
<p><em>ruok</em> : Tests if server is running in a non-error state. The server will respond with imok if it is running. Otherwise it will not respond at all. A response of &quot;imok&quot; does not necessarily indicate that the server has joined the quorum, just that the server process is active and bound to the specified client port. Use &quot;stat&quot; for details on state wrt quorum and client connection information.</p>
</li>
<li>
<p><em>srst</em> : Reset server statistics.</p>
</li>
<li>
<p><em>srvr</em> : <strong>New in 3.3.0:</strong> Lists full details for the server.</p>
</li>
<li>
<p><em>stat</em> : Lists brief details for the server and connected clients.</p>
</li>
<li>
<p><em>wchs</em> : <strong>New in 3.3.0:</strong> Lists brief information on watches for the server.</p>
</li>
<li>
<p><em>wchc</em> : <strong>New in 3.3.0:</strong> Lists detailed information on watches for the server, by session.  This outputs a list of sessions(connections) with associated watches (paths). Note, depending on the number of watches this operation may be expensive (ie impact server performance), use it carefully.</p>
</li>
<li>
<p><em>dirs</em> : <strong>New in 3.5.1:</strong> Shows the total size of snapshot and log files in bytes</p>
</li>
<li>
<p><em>wchp</em> : <strong>New in 3.3.0:</strong> Lists detailed information on watches for the server, by path. This outputs a list of paths (znodes) with associated sessions. Note, depending on the number of watches this operation may be expensive (ie impact server performance), use it carefully.</p>
</li>
<li>
<p><em>mntr</em> : <strong>New in 3.4.0:</strong> Outputs a list of variables that could be used for monitoring the health of the cluster.</p>
<p>$ echo mntr | nc localhost 2185 zk_version  3.4.0 zk_avg_latency  0 zk_max_latency  0 zk_min_latency  0 zk_packets_received 70 zk_packets_sent 69 zk_num_alive_connections 1 zk_outstanding_requests 0 zk_server_state leader zk_znode_count   4 zk_watch_count  0 zk_ephemerals_count 0 zk_approximate_data_size    27 zk_followers    4                   - only exposed by the Leader zk_synced_followers 4               - only exposed by the Leader zk_pending_syncs    0               - only exposed by the Leader zk_open_file_descriptor_count 23    - only available on Unix platforms zk_max_file_descriptor_count 1024   - only available on Unix platforms zk_last_proposal_size 23 zk_min_proposal_size 23 zk_max_proposal_size 64</p>
</li>
</ul>
<p>The output is compatible with java properties format and the content may change over time (new keys added). Your scripts should expect changes. ATTENTION: Some of the keys are platform specific and some of the keys are only exported by the Leader. The output contains multiple lines with the following format:</p>
<pre><code>key \t value
</code></pre>
<ul>
<li>
<p><em>isro</em> : <strong>New in 3.4.0:</strong> Tests if server is running in read-only mode.  The server will respond with &quot;ro&quot; if in read-only mode or &quot;rw&quot; if not in read-only mode.</p>
</li>
<li>
<p><em>gtmk</em> : Gets the current trace mask as a 64-bit signed long value in decimal format.  See <code>stmk</code> for an explanation of the possible values.</p>
</li>
<li>
<p><em>stmk</em> : Sets the current trace mask.  The trace mask is 64 bits, where each bit enables or disables a specific category of trace logging on the server.  Log4J must be configured to enable <code>TRACE</code> level first in order to see trace logging messages.  The bits of the trace mask correspond to the following trace logging categories.</p>
<table>
<thead>
<tr><th> Trace Mask Bit Values </th><th>                     </th></tr>
</thead>
<tbody>
<tr><td> 0b0000000000 </td><td> Unused, reserved for future use. </td></tr>
<tr><td> 0b0000000010 </td><td> Logs client requests, excluding ping requests. </td></tr>
<tr><td> 0b0000000100 </td><td> Unused, reserved for future use. </td></tr>
<tr><td> 0b0000001000 </td><td> Logs client ping requests. </td></tr>
<tr><td> 0b0000010000 </td><td> Logs packets received from the quorum peer that is the current leader, excluding ping requests. </td></tr>
<tr><td> 0b0000100000 </td><td> Logs addition, removal and validation of client sessions. </td></tr>
<tr><td> 0b0001000000 </td><td> Logs delivery of watch events to client sessions. </td></tr>
<tr><td> 0b0010000000 </td><td> Logs ping packets received from the quorum peer that is the current leader. </td></tr>
<tr><td> 0b0100000000 </td><td> Unused, reserved for future use. </td></tr>
<tr><td> 0b1000000000 </td><td> Unused, reserved for future use. </td></tr>
</tbody>
</table>
<p>All remaining bits in the 64-bit value are unused and reserved for future use.  Multiple trace logging categories are specified by calculating the bitwise OR of the documented values. The default trace mask is 0b0100110010.  Thus, by default, trace logging includes client requests, packets received from the leader and sessions. To set a different trace mask, send a request containing the <code>stmk</code> four-letter word followed by the trace mask represented as a 64-bit signed long value.  This example uses the Perl <code>pack</code> function to construct a trace mask that enables all trace logging categories described above and convert it to a 64-bit signed long value with big-endian byte order.  The result is appended to <code>stmk</code> and sent to the server using netcat.  The server responds with the new trace mask in decimal format.</p>
<p>$ perl -e &quot;print 'stmk', pack('q&gt;', 0b0011111010)&quot; | nc localhost 2181 250</p>
</li>
</ul>
<p>Here's an example of the <strong>ruok</strong> command:</p>
<pre><code>$ echo ruok | nc 127.0.0.1 5111
    imok
</code></pre>
<p><a name="sc_adminserver"></a></p>
<h4>The AdminServer</h4>
<p><strong>New in 3.5.0:</strong> The AdminServer is an embedded Jetty server that provides an HTTP interface to the four letter word commands.  By default, the server is started on port 8080, and commands are issued by going to the URL &quot;/commands/[command name]&quot;, e.g., http://localhost:8080/commands/stat.  The command response is returned as JSON.  Unlike the original protocol, commands are not restricted to four-letter names, and commands can have multiple names; for instance, &quot;stmk&quot; can also be referred to as &quot;set_trace_mask&quot;.  To view a list of all available commands, point a browser to the URL /commands (e.g., http://localhost:8080/commands).  See the <a href="#sc_adminserver_config">AdminServer configuration options</a> for how to change the port and URLs.</p>
<p>The AdminServer is enabled by default, but can be disabled by either:</p>
<ul>
<li>Setting the zookeeper.admin.enableServer system property to false.</li>
<li>Removing Jetty from the classpath.  (This option is useful if you would like to override ZooKeeper's jetty dependency.)</li>
</ul>
<p>Note that the TCP four letter word interface is still available if the AdminServer is disabled.</p>
<p><a name="sc_dataFileManagement"></a></p>
<h3>Data File Management</h3>
<p>ZooKeeper stores its data in a data directory and its transaction log in a transaction log directory. By default these two directories are the same. The server can (and should) be configured to store the transaction log files in a separate directory than the data files. Throughput increases and latency decreases when transaction logs reside on a dedicated log devices.</p>
<p><a name="The+Data+Directory"></a></p>
<h4>The Data Directory</h4>
<p>This directory has two or three files in it:</p>
<ul>
<li><em>myid</em> - contains a single integer in human readable ASCII text that represents the server id.</li>
<li><em>initialize</em> - presence indicates lack of data tree is expected. Cleaned up once data tree is created.</li>
<li><em>snapshot.<zxid></em> - holds the fuzzy snapshot of a data tree.</li>
</ul>
<p>Each ZooKeeper server has a unique id. This id is used in two places: the <em>myid</em> file and the configuration file. The <em>myid</em> file identifies the server that corresponds to the given data directory. The configuration file lists the contact information for each server identified by its server id. When a ZooKeeper server instance starts, it reads its id from the <em>myid</em> file and then, using that id, reads from the configuration file, looking up the port on which it should listen.</p>
<p>The <em>snapshot</em> files stored in the data directory are fuzzy snapshots in the sense that during the time the ZooKeeper server is taking the snapshot, updates are occurring to the data tree. The suffix of the <em>snapshot</em> file names is the <em>zxid</em>, the ZooKeeper transaction id, of the last committed transaction at the start of the snapshot. Thus, the snapshot includes a subset of the updates to the data tree that occurred while the snapshot was in process. The snapshot, then, may not correspond to any data tree that actually existed, and for this reason we refer to it as a fuzzy snapshot. Still, ZooKeeper can recover using this snapshot because it takes advantage of the idempotent nature of its updates. By replaying the transaction log against fuzzy snapshots ZooKeeper gets the state of the system at the end of the log.</p>
<p><a name="The+Log+Directory"></a></p>
<h4>The Log Directory</h4>
<p>The Log Directory contains the ZooKeeper transaction logs. Before any update takes place, ZooKeeper ensures that the transaction that represents the update is written to non-volatile storage. A new log file is started when the number of transactions written to the current log file reaches a (variable) threshold. The threshold is computed using the same parameter which influences the frequency of snapshotting (see snapCount above). The log file's suffix is the first zxid written to that log.</p>
<p><a name="sc_filemanagement"></a></p>
<h4>File Management</h4>
<p>The format of snapshot and log files does not change between standalone ZooKeeper servers and different configurations of replicated ZooKeeper servers. Therefore, you can pull these files from a running replicated ZooKeeper server to a development machine with a stand-alone ZooKeeper server for trouble shooting.</p>
<p>Using older log and snapshot files, you can look at the previous state of ZooKeeper servers and even restore that state. The LogFormatter class allows an administrator to look at the transactions in a log.</p>
<p>The ZooKeeper server creates snapshot and log files, but never deletes them. The retention policy of the data and log files is implemented outside of the ZooKeeper server. The server itself only needs the latest complete fuzzy snapshot, all log files following it, and the last log file preceding it.  The latter requirement is necessary to include updates which happened after this snapshot was started but went into the existing log file at that time. This is possible because snapshotting and rolling over of logs proceed somewhat independently in ZooKeeper. See the <a href="#sc_maintenance">maintenance</a> section in this document for more details on setting a retention policy and maintenance of ZooKeeper storage.</p>
<h6>Note</h6>
<blockquote>
<p>The data stored in these files is not encrypted. In the case of storing sensitive data in ZooKeeper, necessary measures need to be taken to prevent unauthorized access. Such measures are external to ZooKeeper (e.g., control access to the files) and depend on the individual settings in which it is being deployed.</p>
</blockquote>
<p><a name="Recovery+-+TxnLogToolkit"></a></p>
<h4>Recovery - TxnLogToolkit</h4>
<p>TxnLogToolkit is a command line tool shipped with ZooKeeper which is capable of recovering transaction log entries with broken CRC.</p>
<p>Running it without any command line parameters or with the <code>-h,--help</code> argument, it outputs the following help page:</p>
<pre><code>$ bin/zkTxnLogToolkit.sh
usage: TxnLogToolkit [-dhrv] txn_log_file_name
-d,--dump      Dump mode. Dump all entries of the log file. (this is the default)
-h,--help      Print help message
-r,--recover   Recovery mode. Re-calculate CRC for broken entries.
-v,--verbose   Be verbose in recovery mode: print all entries, not just fixed ones.
-y,--yes       Non-interactive mode: repair all CRC errors without asking
</code></pre>
<p>The default behaviour is safe: it dumps the entries of the given transaction log file to the screen: (same as using <code>-d,--dump</code> parameter)</p>
<pre><code>$ bin/zkTxnLogToolkit.sh log.100000001
ZooKeeper Transactional Log File with dbid 0 txnlog format version 2
4/5/18 2:15:58 PM CEST session 0x16295bafcc40000 cxid 0x0 zxid 0x100000001 createSession 30000
CRC ERROR - 4/5/18 2:16:05 PM CEST session 0x16295bafcc40000 cxid 0x1 zxid 0x100000002 closeSession null
4/5/18 2:16:05 PM CEST session 0x16295bafcc40000 cxid 0x1 zxid 0x100000002 closeSession null
4/5/18 2:16:12 PM CEST session 0x26295bafcc90000 cxid 0x0 zxid 0x100000003 createSession 30000
4/5/18 2:17:34 PM CEST session 0x26295bafcc90000 cxid 0x0 zxid 0x200000001 closeSession null
4/5/18 2:17:34 PM CEST session 0x16295bd23720000 cxid 0x0 zxid 0x200000002 createSession 30000
4/5/18 2:18:02 PM CEST session 0x16295bd23720000 cxid 0x2 zxid 0x200000003 create '/andor,#626262,v{s{31,s{'world,'anyone}}},F,1
EOF reached after 6 txns.
</code></pre>
<p>There's a CRC error in the 2nd entry of the above transaction log file. In <strong>dump</strong> mode, the toolkit only prints this information to the screen without touching the original file. In <strong>recovery</strong> mode (<code>-r,--recover</code> flag) the original file still remains untouched and all transactions will be copied over to a new txn log file with &quot;.fixed&quot; suffix. It recalculates CRC values and copies the calculated value, if it doesn't match the original txn entry. By default, the tool works interactively: it asks for confirmation whenever CRC error encountered.</p>
<pre><code>$ bin/zkTxnLogToolkit.sh -r log.100000001
ZooKeeper Transactional Log File with dbid 0 txnlog format version 2
CRC ERROR - 4/5/18 2:16:05 PM CEST session 0x16295bafcc40000 cxid 0x1 zxid 0x100000002 closeSession null
Would you like to fix it (Yes/No/Abort) ?
</code></pre>
<p>Answering <strong>Yes</strong> means the newly calculated CRC value will be outputted to the new file. <strong>No</strong> means that the original CRC value will be copied over. <strong>Abort</strong> will abort the entire operation and exits. (In this case the &quot;.fixed&quot; will not be deleted and left in a half-complete state: contains only entries which have already been processed or only the header if the operation was aborted at the first entry.)</p>
<pre><code>$ bin/zkTxnLogToolkit.sh -r log.100000001
ZooKeeper Transactional Log File with dbid 0 txnlog format version 2
CRC ERROR - 4/5/18 2:16:05 PM CEST session 0x16295bafcc40000 cxid 0x1 zxid 0x100000002 closeSession null
Would you like to fix it (Yes/No/Abort) ? y
EOF reached after 6 txns.
Recovery file log.100000001.fixed has been written with 1 fixed CRC error(s)
</code></pre>
<p>The default behaviour of recovery is to be silent: only entries with CRC error get printed to the screen. One can turn on verbose mode with the <code>-v,--verbose</code> parameter to see all records. Interactive mode can be turned off with the <code>-y,--yes</code> parameter. In this case all CRC errors will be fixed in the new transaction file.</p>
<p><a name="sc_commonProblems"></a></p>
<h3>Things to Avoid</h3>
<p>Here are some common problems you can avoid by configuring ZooKeeper correctly:</p>
<ul>
<li>
<p><em>inconsistent lists of servers</em> : The list of ZooKeeper servers used by the clients must match the list of ZooKeeper servers that each ZooKeeper server has. Things work okay if the client list is a subset of the real list, but things will really act strange if clients have a list of ZooKeeper servers that are in different ZooKeeper clusters. Also, the server lists in each Zookeeper server configuration file should be consistent with one another.</p>
</li>
<li>
<p><em>incorrect placement of transaction log</em> : The most performance critical part of ZooKeeper is the transaction log. ZooKeeper syncs transactions to media before it returns a response. A dedicated transaction log device is key to consistent good performance. Putting the log on a busy device will adversely effect performance. If you only have one storage device, put trace files on NFS and increase the snapshotCount; it doesn't eliminate the problem, but it should mitigate it.</p>
</li>
<li>
<p><em>incorrect Java heap size</em> : You should take special care to set your Java max heap size correctly. In particular, you should not create a situation in which ZooKeeper swaps to disk. The disk is death to ZooKeeper. Everything is ordered, so if processing one request swaps the disk, all other queued requests will probably do the same. the disk. DON'T SWAP. Be conservative in your estimates: if you have 4G of RAM, do not set the Java max heap size to 6G or even 4G. For example, it is more likely you would use a 3G heap for a 4G machine, as the operating system and the cache also need memory. The best and only recommend practice for estimating the heap size your system needs is to run load tests, and then make sure you are well below the usage limit that would cause the system to swap.</p>
</li>
<li>
<p><em>Publicly accessible deployment</em> : A ZooKeeper ensemble is expected to operate in a trusted computing environment. It is thus recommended to deploy ZooKeeper behind a firewall.</p>
</li>
</ul>
<p><a name="sc_bestPractices"></a></p>
<h3>Best Practices</h3>
<p>For best results, take note of the following list of good Zookeeper practices:</p>
<p>For multi-tenant installations see the <a href="zookeeperProgrammers.html#ch_zkSessions">section</a> detailing ZooKeeper &quot;chroot&quot; support, this can be very useful when deploying many applications/services interfacing to a single ZooKeeper cluster.</p>
</div>
<div class="clearboth">&nbsp;</div>
</div>
<div id="footer">
    <div class="lastmodified">
        <script type="text/javascript">
        <!--
            document.write("Last Published: " + document.lastModified);
        //  -->
        </script>
    </div>
    <div class="copyright">
        Copyright &copy; <a href="http://www.apache.org/licenses/">The Apache Software Foundation.</a>
    </div>
    <div id="logos"></div>
</div>
</body>
</html>